-------------------------------------------------------------------------------

                          DIRETTIVE DI PROGRAMMAZIONE

-------------------------------------------------------------------------------


 Programmare la libreria gfx3d.library è estremamente semplice. Potenti
funzioni costituiscono l'interfaccia di programmazione della libreria. Al
programmatore non è richiesta alcuna conoscenza di grafica tridimensionale,
quali la manipolazione delle matrici nella graphics pipeline, la trasformazione
delle coordinate (traslazione, rotazione, ecc...) della scena visualizzata e
così via. Compito del programmatore è solo quello di definire le strutture dati
necessarie e modificare le loro proprietà nel tempo. Al tutto il resto penserà
la libreria.

IMPORTANTE:
  Nella versione attuale è possibile aprire la libreria solo da un programma
  per volta. Successive aperture falliranno.

 Normalmente, il codice che fà uso della libreria gfx3d.library è suddivisibile
in due sezioni principali.
 La prima cosa da fare è infatti definire le strutture dati della scena.
Identificheremo questa fase come 'sezione di definizione' di una struttura
dati.
 Successivamente, una volta definite tutte le strutture dati necessarie, sarà
possibile utilizzare tali strutture al fine di aggiornare dinamicamente la
scena visualizzata. Identificheremo questa fase come 'sezione di gestione'
delle strutture dati definite.

 Attualmente (gfx3d.library v2.x), una sezione di definizione inizia sempre con
la funzione GFXBegin() e termina con la funzione GFXEnd(). Le struttura dati
necessarie ad un corretto funzionamento della libreria sono le seguenti:

  - una telecamera (Camera), che fornisce la vista della scena;

  - un ambiente (Environment), contenente gli oggetti da visualizzare. Ogni
    telecamera fà infatti riferimento ad un ambiente;

  - uno o più oggetti (Object), costituenti a tutti gli effetti ciò che si deve
    vedere nella scena;

  - uno o più fotogrammi (Frame), costituenti quello che ogni oggetto
    rappresenta;

  - uno o più poligoni (Polygon), dei quali sono composti i singoli fotogrammi.

A partire dalla versione 2.0 è stata aggiunta la seguente struttura dati:

  - una tabella delle sfumature (ShadeTable), associata all'ambiente ed
    utilizzata per calcolare le sfumature di ogni colore.

 Le precedenti strutture dati si riferiscono solamente ad una scena da
visualizzare. La libreria è però in grado di gestire un numero qualunque di
scene contemporaneamente. Per ogni scena vanno quindi definiti una Camera, un
Environment ed uno o più Objects. Solo le strutture Frames e ShadeTables
possono essere condivise da più scene.

 Le funzioni che vengono utilizzate in una sezione di gestione sono le funzioni
GFXModify...(), le quali si occupano di modificare i parametri delle varie
strutture dati, e le funzioni GFXUpdate...(), che sono adibite ad aggiornare la
scena e l'output video.

 I parametri modificabili di una determinata struttura dati sono solo quelli
specificati dalle funzioni GFXModify...(). E' contro le specifiche modificare
direttamente le strutture dati presenti in memoria, in quanto si è voluta
utilizzare una rappresentazione assimilabile al 'tipo di dato astratto' proprio
della programmazione ad oggetti. In questo modo, qualsiasi modifica interna
delle strutture dati non si ripercuote all'esterno. E' possibile infatti che
differenti versioni e/o revisioni della libreria utilizzino una
rappresentazione interna delle strutture dati differente da quella corrente, al
fine di ottimizzare la velocità generale.

 Lo stesso ragionamento si applica alla rappresentazione interna dei numeri
reali. Dal momento che non tutti gli Amiga dispongono di una FPU, attualmente
i numeri reali vengono rappresentati in virgola fissa nel formato 16bit/16bit .
E' però possibile che diverse versioni e/o revisioni della libreria supportino
l'FPU di alcuni processori (ad esempio in versioni per lo 060), quindi, per
specifica di compatibilità, è consigliato l'utilizzo delle numerose funzioni
matematiche offerte dalla libreria. In ogni caso, è possibile sapere il
supporto o meno dell'FPU tramite la funzione GFXFeatures(). Si noti però che il
tempo perso in chamate alle funzioni matematiche è TOTALMENTE TRASCURABILE
rispetto al tempo necessario a visualizzare la scena...